home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2001 May / SGI IRIX Base Documentation 2001 May.iso / usr / share / catman / u_man / cat3 / Tcl / trace.z / trace
Encoding:
Text File  |  1998-10-30  |  8.6 KB  |  199 lines
  1.  
  2.  
  3.  
  4. ttttrrrraaaacccceeee((((3333TTTTccccllll))))                                                        ttttrrrraaaacccceeee((((3333TTTTccccllll))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      trace - Monitor variable accesses
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      ttttrrrraaaacccceeee _o_p_t_i_o_n ?_a_r_g _a_r_g ...?
  13.  
  14.  
  15. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  16.      This command causes Tcl commands to be executed whenever certain
  17.      operations are invoked.  At present, only variable tracing is
  18.      implemented. The legal _o_p_t_i_o_n's (which may be abbreviated) are:
  19.  
  20.      ttttrrrraaaacccceeee vvvvaaaarrrriiiiaaaabbbblllleeee _n_a_m_e _o_p_s _c_o_m_m_a_n_d
  21.           Arrange for _c_o_m_m_a_n_d to be executed whenever variable _n_a_m_e is
  22.           accessed in one of the ways given by _o_p_s.  _N_a_m_e may refer to a
  23.           normal variable, an element of an array, or to an array as a whole
  24.           (i.e. _n_a_m_e may be just the name of an array, with no parenthesized
  25.           index).  If _n_a_m_e refers to a whole array, then _c_o_m_m_a_n_d is invoked
  26.           whenever any element of the array is manipulated.
  27.  
  28.           _O_p_s indicates which operations are of interest, and consists of one
  29.           or more of the following letters:
  30.  
  31.                rrrr    Invoke _c_o_m_m_a_n_d whenever the variable is read.
  32.  
  33.                wwww    Invoke _c_o_m_m_a_n_d whenever the variable is written.
  34.  
  35.                uuuu    Invoke _c_o_m_m_a_n_d whenever the variable is unset.  Variables
  36.                     can be unset explicitly with the uuuunnnnsssseeeetttt command, or
  37.                     implicitly when procedures return (all of their local
  38.                     variables are unset).  Variables are also unset when
  39.                     interpreters are deleted, but traces will not be invoked
  40.                     because there is no interpreter in which to execute them.
  41.  
  42.           When the trace triggers, three arguments are appended to _c_o_m_m_a_n_d so
  43.           that the actual command is as follows:
  44.  
  45.                _c_o_m_m_a_n_d _n_a_m_e_1 _n_a_m_e_2 _o_p
  46.  
  47.           _N_a_m_e_1 and _n_a_m_e_2 give the name(s) for the variable being accessed:
  48.           if the variable is a scalar then _n_a_m_e_1 gives the variable's name and
  49.           _n_a_m_e_2 is an empty string; if the variable is an array element then
  50.           _n_a_m_e_1 gives the name of the array and name2 gives the index into the
  51.           array; if an entire array is being deleted and the trace was
  52.           registered on the overall array, rather than a single element, then
  53.           _n_a_m_e_1 gives the array name and _n_a_m_e_2 is an empty string.  _O_p
  54.           indicates what operation is being performed on the variable, and is
  55.           one of rrrr, wwww, or uuuu as defined above.
  56.  
  57.           _C_o_m_m_a_n_d executes in the same context as the code that invoked the
  58.           traced operation:  if the variable was accessed as part of a Tcl
  59.           procedure, then _c_o_m_m_a_n_d will have access to the same local variables
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. ttttrrrraaaacccceeee((((3333TTTTccccllll))))                                                        ttttrrrraaaacccceeee((((3333TTTTccccllll))))
  71.  
  72.  
  73.  
  74.           as code in the procedure.  This context may be different than the
  75.           context in which the trace was created.  If _c_o_m_m_a_n_d invokes a
  76.           procedure (which it normally does) then the procedure will have to
  77.           use uuuuppppvvvvaaaarrrr or uuuupppplllleeeevvvveeeellll if it wishes to access the traced variable.
  78.           Note also that _n_a_m_e_1 may not necessarily be the same as the name
  79.           used to set the trace on the variable;  differences can occur if the
  80.           access is made through a variable defined with the uuuuppppvvvvaaaarrrr command.
  81.  
  82.           For read and write traces, _c_o_m_m_a_n_d can modify the variable to affect
  83.           the result of the traced operation.  If _c_o_m_m_a_n_d modifies the value
  84.           of a variable during a read or write trace, then the new value will
  85.           be returned as the result of the traced operation.  The return value
  86.           from  _c_o_m_m_a_n_d is ignored except that if it returns an error of any
  87.           sort then the traced operation also returns an error with the same  |
  88.           error message returned by the trace command (this mechanism can be
  89.           used to implement read-only variables, for example).  For write
  90.           traces, _c_o_m_m_a_n_d is invoked after the variable's value has been
  91.           changed; it can write a new value into the variable to override the
  92.           original value specified in the write operation.  To implement
  93.           read-only variables, _c_o_m_m_a_n_d will have to restore the old value of
  94.           the variable.
  95.  
  96.           While _c_o_m_m_a_n_d is executing during a read or write trace, traces on
  97.           the variable are temporarily disabled.  This means that reads and
  98.           writes invoked by _c_o_m_m_a_n_d will occur directly, without invoking
  99.           _c_o_m_m_a_n_d (or any other traces) again.  However, if _c_o_m_m_a_n_d unsets the|
  100.           variable then unset traces will be invoked.
  101.  
  102.           When an unset trace is invoked, the variable has already been
  103.           deleted:  it will appear to be undefined with no traces.  If an
  104.           unset occurs because of a procedure return, then the trace will be
  105.           invoked in the variable context of the procedure being returned to:
  106.           the stack frame of the returning procedure will no longer exist.
  107.           Traces are not disabled during unset traces, so if an unset trace
  108.           command creates a new trace and accesses the variable, the trace
  109.           will be invoked.  Any errors in unset traces are ignored.           |
  110.  
  111.           If there are multiple traces on a variable they are invoked in order
  112.           of creation, most-recent first.  If one trace returns an error, then
  113.           no further traces are invoked for the variable.  If an array element
  114.           has a trace set, and there is also a trace set on the array as a
  115.           whole, the trace on the overall array is invoked before the one on
  116.           the element.
  117.  
  118.           Once created, the trace remains in effect either until the trace is
  119.           removed with the ttttrrrraaaacccceeee vvvvddddeeeelllleeeetttteeee command described below, until the
  120.           variable is unset, or until the interpreter is deleted.  Unsetting
  121.           an element of array will remove any traces on that element, but will
  122.           not remove traces on the overall array.
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. ttttrrrraaaacccceeee((((3333TTTTccccllll))))                                                        ttttrrrraaaacccceeee((((3333TTTTccccllll))))
  137.  
  138.  
  139.  
  140.           This command returns an empty string.
  141.  
  142.      ttttrrrraaaacccceeee vvvvddddeeeelllleeeetttteeee _n_a_m_e _o_p_s _c_o_m_m_a_n_d
  143.           If there is a trace set on variable _n_a_m_e with the operations and
  144.           command given by _o_p_s and _c_o_m_m_a_n_d, then the trace is removed, so that
  145.           _c_o_m_m_a_n_d will never again be invoked.  Returns an empty string.
  146.  
  147.      ttttrrrraaaacccceeee vvvviiiinnnnffffoooo _n_a_m_e
  148.           Returns a list containing one element for each trace currently set
  149.           on variable _n_a_m_e.  Each element of the list is itself a list
  150.           containing two elements, which are the _o_p_s and _c_o_m_m_a_n_d associated
  151.           with the trace.  If _n_a_m_e doesn't exist or doesn't have any traces
  152.           set, then the result of the command will be an empty string.
  153.  
  154.  
  155. KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS
  156.      read, variable, write, trace, unset
  157.  
  158.  
  159.  
  160.  
  161.  
  162.  
  163.  
  164.  
  165.  
  166.  
  167.  
  168.  
  169.  
  170.  
  171.  
  172.  
  173.  
  174.  
  175.  
  176.  
  177.  
  178.  
  179.  
  180.  
  181.  
  182.  
  183.  
  184.  
  185.  
  186.  
  187.  
  188.  
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.